From f2b482ef657be5292df48b6752a1574c5d0aa3b7 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 19 Feb 2021 15:28:51 -0500 Subject: [PATCH] levelbar: Convert docs Change link syntax, add an example image, generally clean things up. --- gtk/gtklevelbar.c | 148 ++++++++++++++++++++++++---------------------- 1 file changed, 77 insertions(+), 71 deletions(-) diff --git a/gtk/gtklevelbar.c b/gtk/gtklevelbar.c index a44ad4a4e1..f34dd111d9 100644 --- a/gtk/gtklevelbar.c +++ b/gtk/gtklevelbar.c @@ -23,12 +23,14 @@ * @Title: GtkLevelBar * @Short_description: A bar that can used as a level indicator * - * The #GtkLevelBar is a bar widget that can be used + * The `GtkLevelBar` is a bar widget that can be used * as a level indicator. Typical use cases are displaying the strength * of a password, or showing the charge level of a battery. * - * Use gtk_level_bar_set_value() to set the current value, and - * gtk_level_bar_add_offset_value() to set the value offsets at which + * ![An example GtkLevelBar](levelbar.png) + * + * Use [method@Gtk.LevelBar.set_value] to set the current value, and + * [method@Gtk.LevelBar.add_offset_value] to set the value offsets at which * the bar will be considered in a different state. GTK will add a few * offsets by default on the level bar: #GTK_LEVEL_BAR_OFFSET_LOW, * #GTK_LEVEL_BAR_OFFSET_HIGH and #GTK_LEVEL_BAR_OFFSET_FULL, with @@ -40,8 +42,7 @@ * * ## Adding a custom offset on the bar * - * |[ - * + * ```c * static GtkWidget * * create_level_bar (void) * { @@ -71,25 +72,25 @@ * * return widget; * } - * ]| + * ``` * - * The default interval of values is between zero and one, but it’s possible to - * modify the interval using gtk_level_bar_set_min_value() and - * gtk_level_bar_set_max_value(). The value will be always drawn in proportion to - * the admissible interval, i.e. a value of 15 with a specified interval between - * 10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1. - * When #GTK_LEVEL_BAR_MODE_DISCRETE is used, the bar level is rendered - * as a finite number of separated blocks instead of a single one. The number - * of blocks that will be rendered is equal to the number of units specified by - * the admissible interval. + * The default interval of values is between zero and one, but it’s possible + * to modify the interval using [method@Gtk.LevelBar.set_min_value] and + * [method@Gtk.LevelBar.set_max_value]. The value will be always drawn in + * proportion to the admissible interval, i.e. a value of 15 with a specified + * interval between 10 and 20 is equivalent to a value of 0.5 with an interval + * between 0 and 1. When #GTK_LEVEL_BAR_MODE_DISCRETE is used, the bar level + * is rendered as a finite number of separated blocks instead of a single one. + * The number of blocks that will be rendered is equal to the number of units + * specified by the admissible interval. * * For instance, to build a bar rendered with five blocks, it’s sufficient to - * set the minimum value to 0 and the maximum value to 5 after changing the indicator - * mode to discrete. + * set the minimum value to 0 and the maximum value to 5 after changing the + * indicator mode to discrete. * * # GtkLevelBar as GtkBuildable * - * The GtkLevelBar implementation of the GtkBuildable interface supports a + * The `GtkLevelBar` implementation of the `GtkBuildable` interface supports a * custom element, which can contain any number of elements, * each of which must have name and value attributes. * @@ -104,7 +105,7 @@ * ┊ * ]| * - * GtkLevelBar has a main CSS node with name levelbar and one of the style + * `GtkLevelBar` has a main CSS node with name levelbar and one of the style * classes .discrete or .continuous and a subnode with name trough. Below the * trough node are a number of nodes with name block and style class .filled * or .empty. In continuous mode, there is exactly one node of each, in discrete @@ -117,7 +118,7 @@ * * # Accessibility * - * GtkLevelBar uses the #GTK_ACCESSIBLE_ROLE_METER role. + * `GtkLevelBar` uses the #GTK_ACCESSIBLE_ROLE_METER role. */ #include "config.h" @@ -913,11 +914,13 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar::offset-changed: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @name: the name of the offset that changed value * - * Emitted when an offset specified on the bar changes value as an - * effect to gtk_level_bar_add_offset_value() being called. + * Emitted when an offset specified on the bar changes value. + * + * This typically is the result of a [method@Gtk.LevelBar.add_offset_value] + * call. * * The signal supports detailed connections; you can connect to the * detailed signal "changed::x" in order to only receive callbacks when @@ -936,8 +939,7 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar:value: * - * The #GtkLevelBar:value property determines the currently - * filled value of the level bar. + * Determines the currently filled value of the level bar. */ properties[PROP_VALUE] = g_param_spec_double ("value", @@ -949,8 +951,7 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar:min-value: * - * The #GtkLevelBar:min-value property determines the minimum value of - * the interval that can be displayed by the bar. + * Determines the minimum value of the interval that can be displayed by the bar. */ properties[PROP_MIN_VALUE] = g_param_spec_double ("min-value", @@ -962,8 +963,7 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar:max-value: * - * The #GtkLevelBar:max-value property determaxes the maximum value of - * the interval that can be displayed by the bar. + * Determines the maximum value of the interval that can be displayed by the bar. */ properties[PROP_MAX_VALUE] = g_param_spec_double ("max-value", @@ -975,14 +975,16 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar:mode: * - * The #GtkLevelBar:mode property determines the way #GtkLevelBar - * interprets the value properties to draw the level fill area. + * Determines the way `GtkLevelBar` interprets the value properties to draw the + * level fill area. + * * Specifically, when the value is #GTK_LEVEL_BAR_MODE_CONTINUOUS, - * #GtkLevelBar will draw a single block representing the current value in + * `GtkLevelBar` will draw a single block representing the current value in * that area; when the value is #GTK_LEVEL_BAR_MODE_DISCRETE, * the widget will draw a succession of separate blocks filling the * draw area, with the number of blocks being equal to the units separating - * the integral roundings of #GtkLevelBar:min-value and #GtkLevelBar:max-value. + * the integral roundings of [property@Gtk.LevelBar:min-value] and + * [property@Gtk.LevelBar:max-value]. */ properties[PROP_MODE] = g_param_spec_enum ("mode", @@ -995,6 +997,8 @@ gtk_level_bar_class_init (GtkLevelBarClass *klass) /** * GtkLevelBar:inverted: * + * Whether the `GtkLeveBar` is inverted. + * * Level bars normally grow from top to bottom or left to right. * Inverted level bars grow in the opposite direction. */ @@ -1056,9 +1060,9 @@ gtk_level_bar_init (GtkLevelBar *self) /** * gtk_level_bar_new: * - * Creates a new #GtkLevelBar. + * Creates a new `GtkLevelBar`. * - * Returns: a #GtkLevelBar. + * Returns: a `GtkLevelBar`. */ GtkWidget * gtk_level_bar_new (void) @@ -1071,10 +1075,9 @@ gtk_level_bar_new (void) * @min_value: a positive value * @max_value: a positive value * - * Utility constructor that creates a new #GtkLevelBar for the specified - * interval. + * Creates a new `GtkLevelBar` for the specified interval. * - * Returns: a #GtkLevelBar + * Returns: a `GtkLevelBar` */ GtkWidget * gtk_level_bar_new_for_interval (double min_value, @@ -1088,9 +1091,9 @@ gtk_level_bar_new_for_interval (double min_value, /** * gtk_level_bar_get_min_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * - * Returns the value of the #GtkLevelBar:min-value property. + * Returns the `min-value of the `GtkLevelBar`. * * Returns: a positive value */ @@ -1104,9 +1107,9 @@ gtk_level_bar_get_min_value (GtkLevelBar *self) /** * gtk_level_bar_get_max_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * - * Returns the value of the #GtkLevelBar:max-value property. + * Returns the `max-value` of the `GtkLevelBar`. * * Returns: a positive value */ @@ -1120,12 +1123,12 @@ gtk_level_bar_get_max_value (GtkLevelBar *self) /** * gtk_level_bar_get_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * - * Returns the value of the #GtkLevelBar:value property. + * Returns the `value` of the `GtkLevelBar`. * * Returns: a value in the interval between - * #GtkLevelBar:min-value and #GtkLevelBar:max-value + * `GtkLevelBar`:min-value and `GtkLevelBar`:max-value */ double gtk_level_bar_get_value (GtkLevelBar *self) @@ -1148,10 +1151,10 @@ gtk_level_bar_set_value_internal (GtkLevelBar *self, /** * gtk_level_bar_set_min_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @value: a positive value * - * Sets the value of the #GtkLevelBar:min-value property. + * Sets the `min-value` of the `GtkLevelBar`. * * You probably want to update preexisting level offsets after calling * this function. @@ -1184,10 +1187,10 @@ gtk_level_bar_set_min_value (GtkLevelBar *self, /** * gtk_level_bar_set_max_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @value: a positive value * - * Sets the value of the #GtkLevelBar:max-value property. + * Sets the `max-value` of the `GtkLevelBar`. * * You probably want to update preexisting level offsets after calling * this function. @@ -1221,11 +1224,11 @@ gtk_level_bar_set_max_value (GtkLevelBar *self, /** * gtk_level_bar_set_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @value: a value in the interval between - * #GtkLevelBar:min-value and #GtkLevelBar:max-value + * [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] * - * Sets the value of the #GtkLevelBar:value property. + * Sets the value of the `GtkLevelBar`. */ void gtk_level_bar_set_value (GtkLevelBar *self, @@ -1246,11 +1249,11 @@ gtk_level_bar_set_value (GtkLevelBar *self, /** * gtk_level_bar_get_mode: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * - * Returns the value of the #GtkLevelBar:mode property. + * Returns the `mode` of the `GtkLevelBar`. * - * Returns: a #GtkLevelBarMode + * Returns: a `GtkLevelBarMode` */ GtkLevelBarMode gtk_level_bar_get_mode (GtkLevelBar *self) @@ -1262,10 +1265,10 @@ gtk_level_bar_get_mode (GtkLevelBar *self) /** * gtk_level_bar_set_mode: - * @self: a #GtkLevelBar - * @mode: a #GtkLevelBarMode + * @self: a `GtkLevelBar` + * @mode: a `GtkLevelBarMode` * - * Sets the value of the #GtkLevelBar:mode property. + * Sets the `mode` of the `GtkLevelBar`. */ void gtk_level_bar_set_mode (GtkLevelBar *self, @@ -1288,9 +1291,9 @@ gtk_level_bar_set_mode (GtkLevelBar *self, /** * gtk_level_bar_get_inverted: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * - * Return the value of the #GtkLevelBar:inverted property. + * Returns whether the levelbar is inverted. * * Returns: %TRUE if the level bar is inverted */ @@ -1304,10 +1307,10 @@ gtk_level_bar_get_inverted (GtkLevelBar *self) /** * gtk_level_bar_set_inverted: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @inverted: %TRUE to invert the level bar * - * Sets the value of the #GtkLevelBar:inverted property. + * Sets whether the `GtkLevelBar` is inverted. */ void gtk_level_bar_set_inverted (GtkLevelBar *self, @@ -1326,11 +1329,13 @@ gtk_level_bar_set_inverted (GtkLevelBar *self, /** * gtk_level_bar_remove_offset_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @name: (allow-none): the name of an offset in the bar * - * Removes an offset marker previously added with - * gtk_level_bar_add_offset_value(). + * Removes an offset marker from a `GtkLevelBar`. + * + * The marker must have been previously added with + * [method@Gtk.LevelBar.add_offset_value]. */ void gtk_level_bar_remove_offset_value (GtkLevelBar *self, @@ -1352,15 +1357,17 @@ gtk_level_bar_remove_offset_value (GtkLevelBar *self, /** * gtk_level_bar_add_offset_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @name: the name of the new offset * @value: the value for the new offset * * Adds a new offset marker on @self at the position specified by @value. + * * When the bar value is in the interval topped by @value (or between @value - * and #GtkLevelBar:max-value in case the offset is the last one on the bar) - * a style class named `level-`@name will be applied + * and [property@Gtk.LevelBar:max-value] in case the offset is the last one + * on the bar) a style class named `level-`@name will be applied * when rendering the level bar fill. + * * If another offset marker named @name exists, its value will be * replaced by @value. */ @@ -1384,12 +1391,11 @@ gtk_level_bar_add_offset_value (GtkLevelBar *self, /** * gtk_level_bar_get_offset_value: - * @self: a #GtkLevelBar + * @self: a `GtkLevelBar` * @name: (allow-none): the name of an offset in the bar * @value: (out): location where to store the value * - * Fetches the value specified for the offset marker @name in @self, - * returning %TRUE in case an offset named @name was found. + * Fetches the value specified for the offset marker @name in @self. * * Returns: %TRUE if the specified offset is found */ -- 2.30.2